{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "# JSON Prompting\n",
        "In this tutorial, we’ll dive deep into the power of JSON prompting and why it can transform the way you interact with AI models.\n",
        "\n",
        "We will walk you through multiple examples—from simple text prompts to structured JSON prompts—and show you comparisons of their outputs. By the end, you’ll clearly see how structured prompts bring precision, consistency, and scalability to your workflows, whether you’re generating summaries, extracting data, or building advanced AI pipelines."
      ],
      "metadata": {
        "id": "mmS5xb1JCBlQ"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Installing the dependencies"
      ],
      "metadata": {
        "id": "5P_E8CNHCR1q"
      }
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "collapsed": true,
        "id": "7rTMgd9oCFwD",
        "outputId": "77e3fc8a-59b8-4339-b6a5-674665a4a073"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Requirement already satisfied: openai in /usr/local/lib/python3.12/dist-packages (1.100.0)\n",
            "Requirement already satisfied: anyio<5,>=3.5.0 in /usr/local/lib/python3.12/dist-packages (from openai) (4.10.0)\n",
            "Requirement already satisfied: distro<2,>=1.7.0 in /usr/local/lib/python3.12/dist-packages (from openai) (1.9.0)\n",
            "Requirement already satisfied: httpx<1,>=0.23.0 in /usr/local/lib/python3.12/dist-packages (from openai) (0.28.1)\n",
            "Requirement already satisfied: jiter<1,>=0.4.0 in /usr/local/lib/python3.12/dist-packages (from openai) (0.10.0)\n",
            "Requirement already satisfied: pydantic<3,>=1.9.0 in /usr/local/lib/python3.12/dist-packages (from openai) (2.11.7)\n",
            "Requirement already satisfied: sniffio in /usr/local/lib/python3.12/dist-packages (from openai) (1.3.1)\n",
            "Requirement already satisfied: tqdm>4 in /usr/local/lib/python3.12/dist-packages (from openai) (4.67.1)\n",
            "Requirement already satisfied: typing-extensions<5,>=4.11 in /usr/local/lib/python3.12/dist-packages (from openai) (4.14.1)\n",
            "Requirement already satisfied: idna>=2.8 in /usr/local/lib/python3.12/dist-packages (from anyio<5,>=3.5.0->openai) (3.10)\n",
            "Requirement already satisfied: certifi in /usr/local/lib/python3.12/dist-packages (from httpx<1,>=0.23.0->openai) (2025.8.3)\n",
            "Requirement already satisfied: httpcore==1.* in /usr/local/lib/python3.12/dist-packages (from httpx<1,>=0.23.0->openai) (1.0.9)\n",
            "Requirement already satisfied: h11>=0.16 in /usr/local/lib/python3.12/dist-packages (from httpcore==1.*->httpx<1,>=0.23.0->openai) (0.16.0)\n",
            "Requirement already satisfied: annotated-types>=0.6.0 in /usr/local/lib/python3.12/dist-packages (from pydantic<3,>=1.9.0->openai) (0.7.0)\n",
            "Requirement already satisfied: pydantic-core==2.33.2 in /usr/local/lib/python3.12/dist-packages (from pydantic<3,>=1.9.0->openai) (2.33.2)\n",
            "Requirement already satisfied: typing-inspection>=0.4.0 in /usr/local/lib/python3.12/dist-packages (from pydantic<3,>=1.9.0->openai) (0.4.1)\n"
          ]
        }
      ],
      "source": [
        "!pip install openai"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "To get an OpenAI API key, visit https://platform.openai.com/settings/organization/api-keys and generate a new key. If you’re a new user, you may need to add billing details and make a minimum payment of $5 to activate API access."
      ],
      "metadata": {
        "id": "DClkY82iCUkG"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "import os\n",
        "from getpass import getpass\n",
        "os.environ[\"OPENAI_API_KEY\"] = getpass('Enter OpenAI API Key: ')"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "xJPGfgUJCLUh",
        "outputId": "fd63ae89-8634-45d5-fd7e-ae68ea5e4b98"
      },
      "execution_count": 2,
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "Enter OpenAI API Key: ··········\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "from openai import OpenAI\n",
        "client = OpenAI()"
      ],
      "metadata": {
        "id": "EYIZwSvxCnwh"
      },
      "execution_count": 5,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## 1. Structured Prompts Ensure Consistency\n",
        "Using structured prompts, such as JSON-based formats, forces you to think in terms of fields and values — a true advantage when working with LLMs.\n",
        "\n",
        "By defining a fixed structure, you eliminate ambiguity and guesswork, ensuring that every response follows a predictable pattern.\n",
        "\n",
        "Here’s a simple example:\n",
        "```\n",
        "Summarize the following email and list the action items clearly.\n",
        "\n",
        "Email:\n",
        "Hi team, let's finalize the marketing plan by Tuesday. Alice, prepare the draft; Bob, handle the design.\n",
        "```\n",
        "We’ll feed this prompt to the LLM in two ways and then compare the outputs generated by a free-form prompt versus a structured (JSON-based) prompt to observe the difference in clarity and consistency."
      ],
      "metadata": {
        "id": "aGtAh35kCadS"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Free-Form Prompt"
      ],
      "metadata": {
        "id": "QTchS1NVEFj3"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "prompt_text = \"\"\"\n",
        "Summarize the following email and list the action items clearly.\n",
        "\n",
        "Email:\n",
        "Hi team, let's finalize the marketing plan by Tuesday. Alice, prepare the draft; Bob, handle the design.\n",
        "\"\"\"\n",
        "\n",
        "response_text = client.chat.completions.create(\n",
        "    model=\"gpt-5\",\n",
        "    messages=[{\"role\": \"user\", \"content\": prompt_text}]\n",
        ")\n",
        "\n",
        "text_output = response_text.choices[0].message.content\n",
        "print(text_output)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "DUo0F3YqFKJ5",
        "outputId": "006f6e6e-f45e-4191-cbef-0ad06f88874d"
      },
      "execution_count": 13,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Summary:\n",
            "The team needs to finalize the marketing plan by Tuesday. Alice will prepare the draft, and Bob will handle the design.\n",
            "\n",
            "Action items:\n",
            "- Alice: Prepare the draft of the marketing plan by Tuesday.\n",
            "- Bob: Handle the design by Tuesday.\n",
            "- Team: Finalize the marketing plan by Tuesday.\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### JSON Prompt"
      ],
      "metadata": {
        "id": "9Gy3G0DeEIfi"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "prompt_json = \"\"\"\n",
        "Summarize the following email and return the output strictly in JSON format:\n",
        "\n",
        "{\n",
        "  \"summary\": \"short summary of the email\",\n",
        "  \"action_items\": [\"task 1\", \"task 2\", \"task 3\"],\n",
        "  \"priority\": \"low | medium | high\"\n",
        "}\n",
        "\n",
        "Email:\n",
        "Hi team, let's finalize the marketing plan by Tuesday. Alice, prepare the draft; Bob, handle the design.\n",
        "\"\"\"\n",
        "\n",
        "response_json = client.chat.completions.create(\n",
        "    model=\"gpt-5\",\n",
        "    messages=[\n",
        "        {\"role\": \"system\", \"content\": \"You are a precise assistant that always replies in valid JSON.\"},\n",
        "        {\"role\": \"user\", \"content\": prompt_json}\n",
        "    ]\n",
        ")\n",
        "\n",
        "json_output = response_json.choices[0].message.content\n",
        "print(json_output)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "kpoXn23xFVuF",
        "outputId": "fb70d2b9-25c1-4fa8-db5f-d1cb6f0f54c9"
      },
      "execution_count": 15,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "{\n",
            "  \"summary\": \"Finalize the marketing plan by Tuesday; Alice to draft and Bob to handle design.\",\n",
            "  \"action_items\": [\n",
            "    \"Alice: prepare the draft\",\n",
            "    \"Bob: handle the design\",\n",
            "    \"Team: finalize the marketing plan by Tuesday\"\n",
            "  ],\n",
            "  \"priority\": \"medium\"\n",
            "}\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "In this example, the use of a structured JSON prompt leads to a clear and concise output that is easy to parse and evaluate. By defining fields such as \"**summary**\", \"**action_items**\", and \"**priority**\", the LLM response becomes more consistent and actionable. Instead of generating free-flowing text, which might vary in style and detail, the model provides a predictable structure that eliminates ambiguity. This approach not only improves the readability and reliability of responses but also makes it easier to integrate the output into downstream workflows, such as project trackers, dashboards, or automated email handlers."
      ],
      "metadata": {
        "id": "0Q_8A560DQh8"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## 2. User can control the output\n",
        "When you frame your prompt in JSON, you remove ambiguity from both the instruction and the output. In this example, asking for a market summary, sentiment, opportunities, risks, and a confidence score can yield inconsistent formats when passed as plain text. However, by structuring the request in JSON — with clearly defined fields like \"summary\", \"sentiment\", \"opportunities\", \"risks\", and \"confidence_score\" — the response becomes predictable, machine-friendly, and easier to parse. This consistency ensures that, whether you’re generating content, analyzing reports, or extracting insights, your workflow remains streamlined and reliable, with no surprises — just clean, structured results every time."
      ],
      "metadata": {
        "id": "GnaGfKirDtWS"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Free-Form Prompt"
      ],
      "metadata": {
        "id": "l8GEEPz0EnSr"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "plain_text_prompt = \"\"\"\n",
        "Analyze the following market update:\n",
        "\n",
        "Market Text:\n",
        "Tesla's Q2 earnings beat expectations due to higher Model Y sales, but rising competition from BYD is a risk.\n",
        "Apple reported steady revenue growth driven by iPhone sales, but services revenue slightly declined.\n",
        "Amazon's AWS division continues to dominate cloud computing, though regulatory scrutiny in Europe is increasing.\n",
        "\n",
        "Generate:\n",
        "- A 2-line market summary\n",
        "- Sentiment for each company (positive, negative, neutral)\n",
        "- Key growth opportunities and risks\n",
        "- A confidence score from 0 to 10\n",
        "\"\"\"\n",
        "\n",
        "response_plain = client.chat.completions.create(\n",
        "    model=\"gpt-5\",\n",
        "    messages=[{\"role\": \"user\", \"content\": plain_text_prompt}]\n",
        ")\n",
        "\n",
        "plain_output = response_plain.choices[0].message.content\n",
        "print(plain_output)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "olhztDhuFzrU",
        "outputId": "527aebf9-0ef0-44e6-d229-d8e95ecd6d85"
      },
      "execution_count": 16,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Market summary:\n",
            "- Earnings updates skew constructive: Tesla beat on Q2 with strong Model Y, Apple grew on iPhone, and AWS remains the cloud leader.\n",
            "- Offsetting risks include BYD pressure on Tesla, Apple’s services dip, and rising European scrutiny on Amazon.\n",
            "\n",
            "Sentiment:\n",
            "- Tesla: Positive\n",
            "- Apple: Neutral\n",
            "- Amazon: Positive\n",
            "\n",
            "Key growth opportunities and risks:\n",
            "- Tesla\n",
            "  - Opportunities: Sustain Model Y momentum; scale production and pricing to drive volume.\n",
            "  - Risks: Intensifying competition from BYD could pressure share and margins.\n",
            "- Apple\n",
            "  - Opportunities: Monetize large iPhone base; re-accelerate services via bundles and ecosystem engagement.\n",
            "  - Risks: Services softness; dependence on iPhone for top-line growth.\n",
            "- Amazon (AWS)\n",
            "  - Opportunities: Leverage leadership to win more enterprise/AI workloads and multi-year commitments.\n",
            "  - Risks: European regulatory scrutiny may lead to fines, compliance costs, or contract/pricing constraints.\n",
            "\n",
            "Confidence score: 7/10\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### JSON Prompt"
      ],
      "metadata": {
        "id": "a9G-ma3ZEqAr"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "json_prompt = \"\"\"\n",
        "Analyze the following market update and return the response in this JSON format:\n",
        "\n",
        "{\n",
        "  \"summary\": \"2-line market overview\",\n",
        "  \"companies\": [\n",
        "    {\n",
        "      \"name\": \"string\",\n",
        "      \"sentiment\": \"positive | negative | neutral\",\n",
        "      \"opportunities\": [\"list of opportunities\"],\n",
        "      \"risks\": [\"list of risks\"]\n",
        "    }\n",
        "  ],\n",
        "  \"confidence_score\": \"integer (0-10)\"\n",
        "}\n",
        "\n",
        "Market Text:\n",
        "Tesla's Q2 earnings beat expectations due to higher Model Y sales, but rising competition from BYD is a risk.\n",
        "Apple reported steady revenue growth driven by iPhone sales, but services revenue slightly declined.\n",
        "Amazon's AWS division continues to dominate cloud computing, though regulatory scrutiny in Europe is increasing.\n",
        "\"\"\"\n",
        "\n",
        "response_json = client.chat.completions.create(\n",
        "    model=\"gpt-5\",\n",
        "    messages=[\n",
        "        {\"role\": \"system\", \"content\": \"You are a precise assistant that always outputs valid JSON.\"},\n",
        "        {\"role\": \"user\", \"content\": json_prompt}\n",
        "    ]\n",
        ")\n",
        "\n",
        "json_output = response_json.choices[0].message.content\n",
        "print(json_output)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "kWe35Q8sF2tX",
        "outputId": "e1456f33-c811-495b-ce6d-87e02d048c24"
      },
      "execution_count": 17,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "{\n",
            "  \"summary\": \"Markets saw mixed corporate updates: Tesla beat expectations on strong Model Y sales and AWS maintained cloud leadership.\\nHowever, Apple’s growth was tempered by softer services revenue while Tesla and AWS face competition and regulatory risks.\",\n",
            "  \"companies\": [\n",
            "    {\n",
            "      \"name\": \"Tesla\",\n",
            "      \"sentiment\": \"positive\",\n",
            "      \"opportunities\": [\n",
            "        \"Leverage strong Model Y demand to drive revenue and scale production\",\n",
            "        \"Sustain earnings momentum from better-than-expected Q2 results\"\n",
            "      ],\n",
            "      \"risks\": [\n",
            "        \"Intensifying competition from BYD\",\n",
            "        \"Potential price pressure impacting margins\"\n",
            "      ]\n",
            "    },\n",
            "    {\n",
            "      \"name\": \"Apple\",\n",
            "      \"sentiment\": \"neutral\",\n",
            "      \"opportunities\": [\n",
            "        \"Build on steady iPhone-driven revenue growth\",\n",
            "        \"Revitalize Services to reaccelerate growth\"\n",
            "      ],\n",
            "      \"risks\": [\n",
            "        \"Slight decline in services revenue\",\n",
            "        \"Reliance on iPhone as the primary growth driver\"\n",
            "      ]\n",
            "    },\n",
            "    {\n",
            "      \"name\": \"Amazon (AWS)\",\n",
            "      \"sentiment\": \"positive\",\n",
            "      \"opportunities\": [\n",
            "        \"Capitalize on cloud leadership to win new enterprise workloads\",\n",
            "        \"Expand higher-margin managed services and deepen customer spend\"\n",
            "      ],\n",
            "      \"risks\": [\n",
            "        \"Increasing regulatory scrutiny in Europe\",\n",
            "        \"Potential compliance costs or operational restrictions\"\n",
            "      ]\n",
            "    }\n",
            "  ],\n",
            "  \"confidence_score\": 8\n",
            "}\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "The free-form prompt produced a useful summary but lacked structure, giving the model too much freedom and making it harder to parse programmatically or integrate into workflows.\n",
        "\n",
        "In contrast, the JSON-prompted result gave the user full control over the output format, ensuring clean, machine-readable results with distinct fields for summary, sentiment, opportunities, risks, and confidence score. This structured approach not only simplifies downstream processing — for dashboards, automated alerts, or data pipelines — but also guarantees consistency across responses. By defining the fields upfront, users effectively guide the model to deliver exactly what they need, reducing ambiguity and improving reliability."
      ],
      "metadata": {
        "id": "eKlQNiJ1FC_n"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## 3. Reusable JSON prompt templates unlock scalability, speed, and clean handoffs.\n",
        "By defining structured fields upfront, teams can generate consistent, machine-readable outputs that plug directly into APIs, databases, or apps without manual formatting. This standardization not only accelerates workflows but also ensures reliable, repeatable results, making collaboration and automation seamless across projects."
      ],
      "metadata": {
        "id": "_tG7nAhVFPEj"
      }
    }
  ]
}